home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / gnats.info-3.z / gnats.info-3
Encoding:
GNU Info File  |  1998-05-21  |  47.3 KB  |  1,369 lines
  1. This is Info file ../../info/gnats.info, produced by Makeinfo version
  2. 1.68 from the input file gnats.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Keeping Track: (gnats).        GNU Problem Report Management System
  6. END-INFO-DIR-ENTRY
  7.  
  8.    Copyright (C) 1993, 1995 Free Software Foundation, Inc.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions.
  22.  
  23. 
  24. File: gnats.info,  Node: rmcat,  Next: gen-index,  Prev: mkcat,  Up: Admin utils
  25.  
  26. Removing a problem category
  27. ---------------------------
  28.  
  29.    To remove a category from the database:
  30.  
  31.   1. Remove the Problem Reports from the subdirectories corresponding
  32.      to the categories you wish to remove, or assign the PRs to new
  33.      categories.  All PRs for a given category reside in
  34.      `GNATS_ROOT/CATEGORY'.  Make sure you do this for each category
  35.      you wish to remove.
  36.  
  37.   2. Run `rmcat' using
  38.  
  39.           rmcat CATEGORY [ CATEGORY... ]
  40.  
  41.      where CATEGORY is the category you wish to remove.  You can
  42.      specify as many categories as you wish as long as each category
  43.      has no PRs associated with it.  `rmcat' removes the directory under
  44.      GNATS_ROOT where the Problem Reports for that category had been
  45.      stored.  `rmcat' also deletes the category from the list of valid
  46.      categories for both your locally installed `send-pr' and for the
  47.      `send-pr' distribution template in `PREFIX/lib/gnats/dist' (*note
  48.      Where GNATS lives: Locations.).
  49.  
  50.    *Note:* `rmcat' does not update the categories list for other
  51. machines on your network which have `send-pr' installed.  *Note
  52. Managing GNATS over a network: Networked management.
  53.  
  54.    It is also important to note that only your local `send-pr' has
  55. access to this new information; any copies of `send-pr' which you have
  56. distributed to outside submitters now have outdated category lists.
  57. You must either contact your submitters and instruct them to update
  58. their copy of the categories list, which they installed in
  59. `PREFIX/lib/gnats/SUPPORT-SITE' (*Note:* the value for PREFIX may be
  60. different from yours) from the distribution you provided, or you must
  61. build another distribution of `send-pr' with this new information and
  62. redistribute it (*note Configuring `send-pr' for the outside world:
  63. mkdist.).
  64.  
  65. 
  66. File: gnats.info,  Node: gen-index,  Next: mkdist,  Prev: rmcat,  Up: Admin utils
  67.  
  68. Regenerating the index
  69. ----------------------
  70.  
  71.    If your `index' file becomes corrupted, or if you need a copy of the
  72. current index for some reason, use
  73.  
  74.      gen-index [ -n | --numeric ]
  75.                [ -d DIRECTORY | --directory=DIRECTORY ]
  76.            [ -c FILENAME | --catfile=FILENAME ]
  77.                [ -o FILENAME | --outfile=FILENAME ]
  78.                [ -h | --help] [ -V | --version ]
  79.  
  80. With no options, `gen-index' generates an index that is ordered the
  81. same as the order of the categories as they appear in the `categories'
  82. file, and prints it to standard output.  The options are:
  83.  
  84. `-n'
  85. `--numeric'
  86.      Sorts index entries numerically.
  87.  
  88. `-d DIRECTORY'
  89. `--directory=DIRECTORY'
  90.      Uses DIRECTORY as the directory containing the database, by
  91.      default GNATS_ROOT (*note Where GNATS lives: Locations.).
  92.  
  93. `-o FILENAME'
  94. `--outfile=FILENAME'
  95.      Places output in FILENAME rather than sending it to standard
  96.      output.
  97.  
  98. `-c FILENAME'
  99. `--catfile=FILENAME'
  100.      Point to FILENAME, the file listing the valid categories.
  101.  
  102. `-h'
  103. `--help'
  104.      Prints the usage for `gen-index'.
  105.  
  106. `-V'
  107. `--version'
  108.      Prints the version number for `gen-index'.
  109.  
  110. 
  111. File: gnats.info,  Node: mkdist,  Prev: gen-index,  Up: Admin utils
  112.  
  113. Configuring `send-pr' for the outside world
  114. -------------------------------------------
  115.  
  116.    Now that GNATS is up and running on your system, you probably want
  117. to distribute `send-pr' to all your friends, relatives, enemies, etc.
  118. so they can more easily submit bugs to your organization.  To do this,
  119. create a new directory DIST-DIRECTORY to hold the distribution.  Then
  120. run the program
  121.  
  122.      mkdist --release=RELEASE DIST-DIRECTORY
  123.  
  124. This populates DIST-DIRECTORY with a full distribution of the program
  125. `send-pr', including a `Makefile' and all the `send-pr' documentation.
  126. You can then simply package up this directory and send it to your bug
  127. report submitters.  For example, when logged in as `gnats' you can do
  128. the following:
  129.  
  130.      mkdir new-dist
  131.      mkdist --release=tools-1.2 new-dist
  132.      tar cvf send-pr.tar new-dist
  133.  
  134.    This creates a file called `send-pr.tar' which contains a full
  135. distribution of `send-pr' customized for your site, with a default
  136. release number of `tools-1.2'.  You can then place this onto a disk or
  137. tape and send it to your submitters, or instruct your submitters to
  138. download it using `ftp'.
  139.  
  140.    If you only have one submitter, you can set the Submitter ID in the
  141. send-pr script by specifying the -submitter option to mkdist.  If you
  142. do this, the submitter will not have to run install-sid.
  143.  
  144. 
  145. File: gnats.info,  Node: Internal utils,  Prev: Admin utils,  Up: Management
  146.  
  147. Internal utilities
  148. ==================
  149.  
  150.    These tools are used internally by GNATS.  You should never need to
  151. run these by hand; however, a complete understanding may help you locate
  152. problems with the GNATS tools or with your local implementation.
  153.  
  154. * Menu:
  155.  
  156. * queue-pr::    Handling incoming traffic
  157. * file-pr::     Processing incoming traffic
  158. * at-pr::       Timely reminders
  159. * pr-edit::     The edit-pr driver
  160. * pr-addr::     Address retrieval
  161.  
  162. 
  163. File: gnats.info,  Node: queue-pr,  Next: file-pr,  Up: Internal utils
  164.  
  165. Handling incoming traffic
  166. -------------------------
  167.  
  168.    The program `queue-pr' handles traffic coming into GNATS.
  169. `queue-pr' queues incoming Problem Reports in the directory
  170. `GNATS_ROOT/gnats-queue', and then periodically (via `cron') passes
  171. them on to `file-pr' to be filed in the GNATS database.  *Note
  172. Installing GNATS: Installation.
  173.  
  174.    The usage for `queue-pr' is as follows:
  175.  
  176.      queue-pr [ -q | --queue ] [ -r | --run ]
  177.               [ -f FILENAME | --file=FILENAME ]
  178.               [ -d DIRECTORY | --directory=DIRECTORY ]
  179.  
  180.    One of `-q' or `-r' (or their longer-named counterparts) must be
  181. present upon each call to `queue-pr'.  These options provide different
  182. functions, as described below.
  183.  
  184. `-q'
  185. `--queue'
  186.      Accepts standard input as an incoming mail message, placing this
  187.      message in an incrementally numbered file in the `gnats-queue'
  188.      directory under `GNATS_ROOT' (*note Where GNATS lives: Locations.).
  189.  
  190. `-r'
  191. `--run'
  192.      Redirects files in the `gnats-queue' directory into the program
  193.      `file-pr' one by one.
  194.  
  195. `-f FILENAME'
  196. `--file=FILENAME'
  197.      Used with `-q' (or `--queue'), accepts the file denoted by
  198.      FILENAME as input rather than reading from standard input.
  199.  
  200. `-d DIRECTORY'
  201. `--directory=DIRECTORY'
  202.      Resets the default DIRECTORY value, which is by default
  203.      `GNATS_ROOT/gnats-queue'.  When `-d DIRECTORY' is used in
  204.      conjunction with the `-q' (or `--queue') option, `queue-pr' files
  205.      incoming messages into DIRECTORY rather than the `gnats-queue'
  206.      directory.  When `-d DIRECTORY' is used in conjunction with the
  207.      `-r' (or `--run') option, `queue-pr' redirects into `file-pr'
  208.      files from DIRECTORY rather than from the `gnats-queue' directory.
  209.  
  210. 
  211. File: gnats.info,  Node: file-pr,  Next: at-pr,  Prev: queue-pr,  Up: Internal utils
  212.  
  213. Processing incoming traffic
  214. ---------------------------
  215.  
  216.    `queue-pr' hands off queued Problem Reports to `file-pr' one at a
  217. time.  `file-pr' checks each Problem Report for correct information in
  218. its fields (particularly a correct `>Category:'), assigns it an
  219. identification number, and files it in the database under the
  220. appropriate category.
  221.  
  222.    If the `>Category:' field does not contain a valid category value
  223. (i.e., matching a line in the `categories' file; *note The `categories'
  224. file: categories.), the PR is given a `>Category:' value of `pending'
  225. and is placed in the `pending' directory.  The GNATS administrator is
  226. notified of the unplaceable PR.
  227.  
  228.    `file-pr' assigns the Problem Report an identification number, files
  229. it in the GNATS database (under `pending', if the `>Category:' field
  230. contains an invalid category), and sends acknowledgements to
  231. appropriate parties.  The person responsible for that category of
  232. problem (*note The `categories' file: categories.) and the person
  233. responsible for the submitter site where the PR originated (*note The
  234. `submitters' file: submitters.) receive a copy of the PR in its
  235. entirety.  Optionally, the originator of the PR receives an
  236. acknowledgement that the PR arrived and was filed (*note Changing your
  237. local configuration: Local configuration.).
  238.  
  239.    The usage for `file-pr' is as follows:
  240.  
  241.      file-pr [ -f FILENAME | --file=FILENAME ]
  242.              [ -d DIRECTORY | --directory=DIRECTORYb ]
  243.          [ -D | --debug ] [ -h | --help ] [ -V | --version ]
  244.  
  245.    `file-pr' requires no options in order to operate, and takes input
  246. from standard input (normally, the output of `queue-pr -r') unless
  247. otherwise specified.  The options include:
  248.  
  249. `-f FILENAME'
  250. `--filename=FILENAME'
  251.      Uses FILENAME as input rather than standard input.
  252.  
  253. `-d DIRECTORY'
  254. `--directory=DIRECTORY'
  255.      Performs refiling operations in DIRECTORY rather than in
  256.      `GNATS_ROOT'.
  257.  
  258. `-D'
  259. `--debug'
  260.      Give debugging output while `file-pr' is running.
  261.  
  262. `-h'
  263. `--help'
  264.      Prints the usage for `file-pr'.
  265.  
  266. `-V'
  267. `--version'
  268.      Prints the version number for `file-pr'.
  269.  
  270. 
  271. File: gnats.info,  Node: at-pr,  Next: pr-edit,  Prev: file-pr,  Up: Internal utils
  272.  
  273. Timely reminders
  274. ----------------
  275.  
  276.    `at-pr' creates a queued job using `at' which, after an allotted
  277. "response time" is past, checks the PR to see if its state has changed
  278. from `open'.
  279.  
  280.    The `submitters' file contains the response time for each
  281. `>Submitter-Id:' (*note The `submitters' file: submitters.).  The time
  282. is determined in "business hours", which are defined by default as
  283. 8:00am to 5:00pm Monday through Friday, local time.  These hours are
  284. defined in the `config' file (*note The `config' file: config.).
  285.  
  286.    If the PR is still open after the requisite time period has passed,
  287. `at-pr' sends a reminder to the GNATS administrator, to the maintainer
  288. responsible for that submitter, and to the maintainer responsible for
  289. the PR with the following message:
  290.  
  291.      To: SUBMITTER-CONTACT RESPONSIBLE GNATS-ADMIN
  292.      Subject: PR GNATS-ID not analyzed in #HOURS hours
  293.      
  294.      PR GNATS-ID was not analyzed within the acknowledgment period
  295.      of #HOURS business hours.  The pertinent information is:
  296.      
  297.       Submitter-Id: SUBMITTER
  298.       Originator: FULL NAME OF THE SUBMITTER
  299.       Synopsis: SYNOPSIS
  300.       Person responsible for the PR: RESPONSIBLE
  301.      
  302.      --
  303.      The GNU Problem Report Management System (GNATS)
  304.  
  305. 
  306. File: gnats.info,  Node: pr-edit,  Next: pr-addr,  Prev: at-pr,  Up: Internal utils
  307.  
  308. The `edit-pr' driver
  309. --------------------
  310.  
  311.    `pr-edit' does the background work for `edit-pr', including
  312. error-checking and refiling newly edited Problem Reports and handling
  313. file locks.  It can be called interactively, though it has no useable
  314. editing interface.
  315.  
  316.    The usage for `pr-edit' is:
  317.  
  318.      pr-edit [ -l MAINTAINER --lock=MAINTAINER ]
  319.              [ -u | --unlock ] [ -c | --check ] [ -F ]
  320.          [ -L | --lockdb ] [ -U | --unlockdb ]
  321.              [ -f FILENAME | --filename=FILENAME ]
  322.              [ -d DIRECTORY | --directory=DIRECTORY ]
  323.              [ -h | --help ] [ -V | --version ]
  324.              [ GNATS-ID ]
  325.  
  326.    A "lock" is placed on a Problem Report while the PR is being edited.
  327. The lock is simply a file in the same directory as the PR, with the name
  328. `GNATS-ID.lock', which contains the name of the maintainer who created
  329. the lock.  MAINTAINER then "owns" the lock, and must remove it before
  330. the PR can be locked again, even by the same MAINTAINER(1).  If a PR is
  331. already locked when you attempt to edit it, `pr-edit' prints an error
  332. message giving the name of the maintainer who is currently editing the
  333. PR.
  334.  
  335.    If you do not specify GNATS-ID, `pr-edit' reads from standard input.
  336. You must specify GNATS-ID for the functions which affect PR locks,
  337. `--lock=MAINTAINER' and `--unlock'.
  338.  
  339. `-l MAINTAINER'
  340. `--lock=MAINTAINER'
  341.      Locks Problem Report GNATS-ID, failing (and returning an error
  342.      message) if GNATS-ID is already locked, or if GNATS-ID does not
  343.      exist.  `pr-edit' requires that you specify GNATS-ID when using
  344.      this option.
  345.  
  346. `-u'
  347. `--unlock'
  348.      Unlocks Problem Report GNATS-ID.  `pr-edit' requires that you
  349.      specify GNATS-ID when using this option.  You must own a file lock
  350.      to remove it.
  351.  
  352. `-L'
  353. `--lockdb'
  354.      Locks the GNATS database as a whole.  This will prevent any
  355.      modification to any part of the system while it's locked.
  356.  
  357. `-U'
  358. `--unlockdb'
  359.      Unlocks the GNATS database as a whole, allowing modification of its
  360.      files.
  361.  
  362. `-c'
  363. `--check'
  364.      Checks the Problem Report in GNATS-ID (or standard input, if
  365.      GNATS-ID is not present) for correct information in its ENUMERATED
  366.      fields.  `pr-edit' complains about any bogus information in the
  367.      Problem Report.
  368.  
  369. `-F'
  370.      Forces the PR to be submitted to the database, even if there is no
  371.      current index entry for it (i.e., even if the PR did not exist in
  372.      the database previously).
  373.  
  374.      *Warning: using this option may corrupt your index.*  If you use
  375.      it, be sure you know what you are doing.
  376.  
  377. `-f FILENAME'
  378. `--filename=FILENAME'
  379.      Reads FILENAME rather than standard input.
  380.  
  381. `-d DIRECTORY'
  382. `--directory=DIRECTORY'
  383.      Resets the operating directory (`GNATS_ROOT').
  384.  
  385. `-h'
  386. `--help'
  387.      Prints the usage for `pr-edit'.
  388.  
  389. `-V'
  390. `--version'
  391.      Prints the version number for `pr-edit'.
  392.  
  393.    ---------- Footnotes ----------
  394.  
  395.    (1) This approach may seem heavy-handed, but it ensures that changes
  396. are not overwritten.
  397.  
  398. 
  399. File: gnats.info,  Node: pr-addr,  Prev: pr-edit,  Up: Internal utils
  400.  
  401. Address retrieval
  402. -----------------
  403.  
  404.    Returns an electronic mail address when given a valid "nametag", as
  405. it appears in the `responsible' file (*note The `responsible' file:
  406. responsible.).  If NAMETAG is not valid, `pr-addr' will tell the user
  407. that it could not find the requested address.
  408.  
  409.    Usage is simply:
  410.  
  411.      pr-addr NAME
  412.  
  413. 
  414. File: gnats.info,  Node: Installation,  Next: Locations,  Prev: Management,  Up: Top
  415.  
  416. Installing GNATS
  417. ****************
  418.  
  419.    *Note Where the tools and utilities reside: Locations.
  420.  
  421.    There are several steps you need to follow to fully configure and
  422. install GNATS on your system.  You need `root' access in order to
  423. create a new account for `gnats' and to install the GNATS utilities.
  424. You may need `root' access on some systems in order to set mail aliases
  425. in place and to allow this new account access to `cron' and `at'.
  426.  
  427.    If you are updating an older version of GNATS rather than installing
  428. from scratch, see *Note Upgrading from older versions: Upgrading.
  429.  
  430.    To build GNATS, you must:
  431.  
  432.    * Run `configure', with correct options if the defaults are
  433.      unsuitable for your site.  *Note Configuring and compiling the
  434.      software: Configure and make.  Default installation locations are
  435.      in *Note Where GNATS lives: Locations.
  436.  
  437.    * Compile the GNATS programs on your system.  *Note Configuring and
  438.      compiling the software: Configure and make.
  439.  
  440.    * Install the GNATS tools and utilities locally, and install the user
  441.      tools on every machine in your local network.  *Note Installing
  442.      the utilities: Installing utils.
  443.  
  444.    * Set up mail aliases for GNATS.  *Note Setting up mail aliases:
  445.      Aliases.
  446.  
  447.    * Install the GNATS user tools (`query-pr', `nquery-pr', `edit-pr',
  448.      `send-pr') around your network.  *Note Installing the user tools:
  449.      Installing tools.
  450.  
  451.    * Install the GNATS daemon `gnatsd'.
  452.  
  453.    * Update the local configuration files
  454.  
  455.           config      categories  submitters  responsible  gnatsd.conf
  456.  
  457.      in `GNATS_ROOT/gnats-adm'.  *Note Changing your local
  458.      configuration: Local configuration.
  459.  
  460.    * Create a distribution of `send-pr' for submitters outside your
  461.      organization.  *Note Configuring `send-pr' for the outside world:
  462.      mkdist.
  463.  
  464. * Menu:
  465.  
  466. * Configure and make::    Configuring and compiling the software
  467. * Installing utils::      Installing the utilities
  468. * Aliases::               Setting up mail aliases
  469. * Installing the daemon:: Installing the daemon
  470. * Installing tools::      Installing the user tools
  471. * Upgrading::             Upgrading from older versions
  472.  
  473. 
  474. File: gnats.info,  Node: Configure and make,  Next: Installing utils,  Up: Installation
  475.  
  476. Configuring and compiling the software
  477. ======================================
  478.  
  479.   1. First, unpack your distribution.  We provide source code in a `tar'
  480.      file which was compressed using `gzip'.  The code can be extracted
  481.      into a directory UNPACKDIR using
  482.  
  483.           mkdir UNPACKDIR
  484.           cd UNPACKDIR
  485.           tar zxvf gnats-3.101.tar.z
  486.  
  487.      The sources reside in a directory called `gnats-3.101' when
  488.      unpacked.  We call this the "top level" of the source directory,
  489.      or "srcdir".  The sources for the GNATS tools are in the
  490.      subdirectory `gnats-3.101/gnats/*'.  Lists of files included in
  491.      the distribution are in each directory in the file `MANIFEST'.
  492.  
  493.   2. You may wish to alter the installation directory for the Emacs lisp
  494.      files.  If your Emacs lisp library is not in
  495.      `PREFIX/lib/emacs/lisp', edit the files
  496.  
  497.           SRCDIR/gnats/Makefile.in   *and*
  498.           SRCDIR/send-pr/Makefile.in
  499.  
  500.      Change the variable `lispdir' from `$(datadir)/emacs/lisp' to the
  501.      directory containing your Emacs lisp library.  For information on
  502.      PREFIX, see *Note PREFIX: prefix.
  503.  
  504.   3. Run `configure'.  You can nearly always run `configure' with the
  505.      command
  506.  
  507.           ./configure --with-full-gnats
  508.  
  509.      and the "Right Thing" happens:
  510.  
  511.         * GNATS is configured in the same directory you unpacked it in;
  512.  
  513.         * when built, GNATS runs on the machine you're building it on;
  514.  
  515.         * when installed, files are installed under `/usr/local' (*note
  516.           Where GNATS lives: Locations.).
  517.  
  518.         * GNATS operates by default behavior (*note Default behavior:
  519.           default behavior.).
  520.  
  521.      The full usage for `configure' is:
  522.  
  523.           configure [ --with-full-gnats ]
  524.                     [ --prefix=PREFIX ]
  525.                     [ --exec-prefix=EXEC-PREFIX ]
  526.                     [ --with-gnats-root=GNATS_ROOT ]
  527.                     [ --with-gnats-server=HOSTNAME ]
  528.                     [ --with-gnats-service=SERVICE-NAME ]
  529.                     [ --with-gnats-user=USERNAME ]
  530.                     [ --with-gnats-port=PORT-NUMBER ]
  531.                     [ --verbose ]
  532.  
  533.     `--with-full-gnats'
  534.           All programs are to be built; this includes the user
  535.           utilities, the administrative utilities, and the internal
  536.           utilities.  Use this when configuring the utilities for the
  537.           machine where GNATS is to run.  Omit it when building only
  538.           the user utilities for other machines on your network; see
  539.           *Note Installing the user tools: Installing tools.
  540.  
  541.     `--prefix=PREFIX'
  542.           All host-independent programs and files are to be installed
  543.           under PREFIX.  (Host-dependent programs and files are also
  544.           installed in PREFIX by default.)  The default for PREFIX is
  545.           `/usr/local'.  *Note Where GNATS lives: Locations.
  546.  
  547.     `--exec-prefix=EXEC-PREFIX'
  548.           All host-dependent programs and files are to be installed
  549.           under EXEC-PREFIX.  The default for EXEC-PREFIX is PREFIX.
  550.           *Note Where GNATS lives: Locations.
  551.  
  552.     `--with-gnats-root=GNATS_ROOT'
  553.           The database and its data files are to be installed into
  554.           GNATS_ROOT.  The default for GNATS_ROOT is
  555.           `PREFIX/lib/gnats/gnats-db'.  *Note Where GNATS lives:
  556.           Locations.
  557.  
  558.     `--with-gnats-root=hostname'
  559.           FIXME
  560.  
  561.     `--with-gnats-root=SERVICE-NAME'
  562.           FIXME
  563.  
  564.     `--with-gnats-user=USERNAME'
  565.           FIXME
  566.  
  567.     `--with-gnats-port=PORT-NUMBER'
  568.           FIXME
  569.  
  570.     `--verbose'
  571.           Give verbose output while `configure' runs.
  572.  
  573.      *Note Using `configure': (configure)Using configure.
  574.  
  575.      You can build GNATS in a different directory (OBJDIR) from the
  576.      source code by calling the `configure' program from the new
  577.      directory, as in
  578.  
  579.           mkdir OBJDIR
  580.           cd OBJDIR
  581.           SRCDIR/configure ...
  582.           make all
  583.  
  584.      By default, `configure' compiles the programs in the same directory
  585.      as the sources (SRCDIR).  Emacs lisp files are byte-compiled if
  586.      `make' can find Emacs on your local system.
  587.  
  588.   4. Run
  589.  
  590.           make all info
  591.  
  592.      from the directory where `configure' created a `Makefile'.  (This
  593.      may not be the same directory as the source directory.)  These
  594.      targets indicate:
  595.  
  596.     `all'
  597.           Compile all programs
  598.  
  599.     `info'
  600.           Create `info' files using `makeinfo'.
  601.  
  602. 
  603. File: gnats.info,  Node: Installing utils,  Next: Aliases,  Prev: Configure and make,  Up: Installation
  604.  
  605. Installing the utilities
  606. ========================
  607.  
  608.    The following steps are necessary for a complete installation.  You
  609. may need `root' access for these.
  610.  
  611.   1. Install the utilities by invoking
  612.  
  613.           make install install-info
  614.  
  615.      These targets indicate:
  616.  
  617.     `install'
  618.           Installs all programs into their configured locations (*note
  619.           Where GNATS lives: Locations.).
  620.  
  621.     `install-info'
  622.           Installs `info' files into their configured locations (*note
  623.           Where GNATS lives: Locations.).
  624.  
  625.      After you have installed GNATS, you can remove the object files
  626.      with
  627.  
  628.           make clean
  629.  
  630.   2. Place the following lines in the file `default.el' in your Emacs
  631.      lisp library, or instruct your local responsible parties to place
  632.      the lines in their local editions of `.emacs':
  633.  
  634.           (autoload 'edit-pr "gnats"
  635.              "Command to edit a problem report." t)
  636.           (autoload 'view-pr "gnats"
  637.              "Command to view a problem report." t)
  638.           (autoload 'unlock-pr "gnats"
  639.              "Unlock a problem report." t)
  640.           (autoload 'query-pr "gnats"
  641.              "Command to query information about problem reports." t)
  642.           (autoload 'send-pr-mode "send-pr"
  643.              "Major mode for sending problem reports." t)
  644.           (autoload 'send-pr "send-pr"
  645.              "Command to create and send a problem report." t)
  646.  
  647.      Emacs lisp files are byte-compiled if `make' can find Emacs on your
  648.      local system.
  649.  
  650.   3. Create an account for a user named GNATS.  This user must have an
  651.      entry in the file `/etc/passwd'.  The home directory for this
  652.      account should be the same directory you specified for GNATS_ROOT
  653.      in the file `Makefile.in'.  Also, the default `PATH' for this user
  654.      should contain `EXEC-PREFIX/bin' and `EXEC-PREFIX/lib/gnats'.
  655.  
  656.   4. Allow the new user `gnats' access to `cron' and `at'.  To do this,
  657.      add the name `gnats' to the files `cron.allow' and `at.allow',
  658.      which normally reside in the directory `/var/spool/cron'.  If
  659.      these files do not exist, make sure `gnats' does not appear in
  660.      either of the files `cron.deny' and `at.deny' (in the same
  661.      directory).
  662.  
  663.      For the following steps, log in as `gnats'.
  664.  
  665.         * Edit the files `categories', `responsible', and `submitters'
  666.           in the directory `GNATS_ROOT/gnats-adm' (*note Changing your
  667.           local configuration: Local configuration.) to reflect your
  668.           local needs.  Be sure to run `mkcat' after you update the
  669.           `categories' file (*note Adding a new problem category:
  670.           mkcat.).  *Note:* these templates are not installed if they
  671.           already exist, i.e. if you are upgrading.  *Note Upgrading
  672.           from older versions: Upgrading.
  673.  
  674.         * If you wish to install the GNATS user tools on other machines
  675.           on your network, see *Note Installing the user tools:
  676.           Installing tools.
  677.  
  678.   5. Create a `crontab' entry that periodically runs the program
  679.      `queue-pr' with the `--run' option.  For example, to run
  680.      `queue-pr --run' every ten minutes, create a file called `.mycron'
  681.      in the home directory of the user `gnats' which contains the line:
  682.  
  683.           0,10,20,30,40,50 * * * * EXEC-PREFIX/lib/gnats/queue-pr --run
  684.  
  685.      (Specify the full path name for `queue-pr'.)  Then run
  686.  
  687.           crontab .mycron
  688.  
  689.      See the `man' pages for `cron' and `crontab' for details on using
  690.      `cron'.
  691.  
  692. 
  693. File: gnats.info,  Node: Aliases,  Next: Installing the daemon,  Prev: Installing utils,  Up: Installation
  694.  
  695. Setting up mail aliases
  696. =======================
  697.  
  698.    The following mail aliases must be placed in the file `/etc/aliases'
  699. on the same machine where the GNATS tools are installed.  You may need
  700. `root' access to add these aliases.
  701.  
  702.    * Create an alias for the GNATS administrator.  This address should
  703.      point to the address of the person in charge of administrating
  704.      GNATS:
  705.  
  706.           gnats-admin:  ADDRESS
  707.  
  708.    * Create an alias to redirect incoming Problem Reports.  This alias
  709.      should redirect incoming mail via a "pipe" to the program
  710.      `queue-pr -q'.  For example, if Problem Reports coming to your
  711.      site are to arrive at the address `bugs@your.company.com', create
  712.      an alias to the effect of:
  713.  
  714.           bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"
  715.  
  716.      This places incoming Problem Reports in `GNATS_ROOT/gnats-queue'.
  717.  
  718.    * Create an alias for your site. This alias should be the same
  719.      nametag indicated by the variable `GNATS_SITE' in the file
  720.      `GNATS_ROOT/gnats-adm/config' (*note The `config' file: config.),
  721.      with an added suffix `-gnats'.  This alias, `GNATS_SITE-gnats',
  722.      should point toward the local submission address.  For instance,
  723.      if your site is Tofu Technologies, the presence of GNATS on your
  724.      SITE would be aliased as the following (the previous example is
  725.      also shown):
  726.  
  727.           bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"
  728.           tofu-gnats: bugs
  729.  
  730.      The report submission utility `send-pr' automatically appends the
  731.      `-gnats' to any arguments you specify (*note Submitting Problem
  732.      Reports: send-pr.).  The `send-pr' which was installed when you
  733.      typed `make install' has a default argument of GNATS_SITE, your
  734.      site, so that when your local users simply type `send-pr' mail is
  735.      sent to your local GNATS.  Part of the installation process a
  736.      Submitter Site follows when installing `send-pr' is to set up an
  737.      alias for the Support Site from whom this submitter received
  738.      `send-pr'.  In other words, anyone you distribute `send-pr' to is
  739.      instructed to make an alias
  740.  
  741.           tofu-gnats: bugs@tofu.com
  742.  
  743.    * You may also wish to forward a copy of each incoming Problem
  744.      Report to a log.  This can be accomplished with something like:
  745.  
  746.           bug-q: "| EXEC-PREFIX/lib/gnats/queue-pr -q"
  747.           bug-log:  GNATS_ROOT/gnats-adm/bugs.log
  748.           bugs:      bug-q, bug-log
  749.  
  750.      This configuration archives incoming Problem Reports in the file
  751.      `GNATS_ROOT/gnats-adm/bug.log', and also feeds them to the program
  752.      `queue-pr'.  (Remember, `bug.log' needs to be world-writable, and
  753.      should be pruned regularly; *note GNATS Administration:
  754.      Management..)
  755.  
  756.    * If you want your users to be able to query the database by mail,
  757.      use the following alias:
  758.  
  759.           query-pr: "| EXEC-PREFIX/lib/gnats/mail-query"
  760.  
  761.      The `mail-query' program uses `--restricted' to search on the
  762.      database, and by default only searches for PRs that aren't closed
  763.      (*note Querying the database: query-pr.).
  764.  
  765. 
  766. File: gnats.info,  Node: Installing the daemon,  Next: Installing tools,  Prev: Aliases,  Up: Installation
  767.  
  768. Installing the daemon
  769. =====================
  770.  
  771.    By default, the daemon and clients are set to use port 1529.  Add
  772. the line
  773.  
  774.      support        1529/tcp            # GNATS
  775.  
  776. to your `/etc/services' file.  If you want a different port, or a
  777. different service name or port, configure GNATS with
  778.  
  779.      --with-gnats-service=SERVICENAME
  780.      --with-gnats-port=PORTNUMBER
  781.  
  782.    In your `inetd.conf' file, add the line
  783.  
  784.      support    stream    tcp    nowait    gnats    /usr/local/lib/gnats/gnatsd gnatsd
  785.  
  786. adjusting the path accordingly.  To make inetd start spawning the GNATS
  787. daemon when connected on that port, send it a hangup signal (`HUP').
  788.  
  789.    By default, the server for the GNATS daemon is assumed to be one
  790. with the name of `gnats'.  If you'd like something else, use
  791.  
  792.      --with-gnats-server=HOSTNAME
  793.  
  794.    In the `gnats-adm' directory, you'll want to edit `gnatsd.conf'.  It
  795. lists the hosts allowed to access your server.  Or, if you're using
  796. Kerberos, it shows the sites that don't require Kerberos authentication.
  797. The format is reserved for future revision; only the first field is
  798. actually used:
  799.  
  800.      site.com::
  801.  
  802. The second field may be used for things like controlling what
  803. categories, submitter-id'd PRs, etc., can be accessed from that site.
  804. In the file that logs syslog messages (`/var/adm/messages', for
  805. example) you'll find the notification of denied access.
  806.  
  807. 
  808. File: gnats.info,  Node: Installing tools,  Next: Upgrading,  Prev: Installing the daemon,  Up: Installation
  809.  
  810. Installing the user tools
  811. =========================
  812.  
  813.    When you install the GNATS utilities, the user tools are installed
  814. by default on the host machine.  If your machine is part of a network,
  815. however, you may wish to install the user tools on each machine in the
  816. network so that responsible parties on those machines can submit new
  817. Problem Reports, query the database, and edit existing PRs.  To do this,
  818. follow these steps *on each new host*.  You may need root access on
  819. each machine.
  820.  
  821.   1. Make sure that the directory where GNATS resides is mounted to each
  822.      system that will need access to it, so GNATS_ROOT will be the same
  823.      for each host.  (You can do this with symbolic links as well.)
  824.  
  825.   2. Either mount the disk which contains your source directory, or
  826.      make a copy of the GNATS source code tree in a separate directory
  827.      on each system you wish to build on.
  828.  
  829.   3. Run `configure', *without* specifying `--with-full-gnats', and
  830.      using the same argument (if any) for the option
  831.  
  832.           --with-gnats-root=GNATS_ROOT
  833.  
  834.      that you specified when building the GNATS utilites (*note
  835.      Configuring and compiling the software: Configure and make.).  You
  836.      may use different values for the other options to `configure'.
  837.      Again, *do not* use `--with-full-gnats' at this point, as that
  838.      creates all the GNATS programs.  Without this option, `configure'
  839.      only instructs the resulting `Makefile' to create the user
  840.      utilities.
  841.  
  842.      *You may need `root' access on each host for the following steps.*
  843.  
  844.   4. Create an account for a user named GNATS on the new host.  This
  845.      user must have an entry in the file `/etc/passwd'.  The user ID for
  846.      `gnats' must be the same as on the main GNATS host.
  847.  
  848.   5. Run
  849.  
  850.           make all info install install-info
  851.  
  852.      This builds and installs the `gnats' user tools `query-pr',
  853.      `edit-pr', and `send-pr' on the new host, and installs them in
  854.      `EXEC-PREFIX/bin' on the new host (*Note:* the value for
  855.      EXEC-PREFIX on the new host may be different from the value you
  856.      used when building the GNATS utilities; *note EXEC-PREFIX:
  857.      exec-prefix.).  The programs `pr-edit' and `pr-addr' are installed
  858.      into `EXEC-PREFIX/lib/gnats'.
  859.  
  860.      `info' files are created as well, and are installed into
  861.      `PREFIX/info'.  The Elisp files `gnats.el' and `send-pr.el' (and
  862.      possibly `gnats.elc' if `make' was able to compile them using
  863.      Emacs) are installed into `PREFIX/lib/emacs/lisp' unless you
  864.      change the `lispdir' variable in `Makefile.in' (*note Configuring
  865.      and compiling the software: Configure and make.).
  866.  
  867.   6. Add the following lines to the file `default.el' in the Emacs lisp
  868.      repository on the new host, or instruct your responsible parties
  869.      who use these hosts to add them to their `.emacs' files:
  870.  
  871.           (autoload 'edit-pr "gnats"
  872.              "Command to edit a problem report." t)
  873.           (autoload 'view-pr "gnats"
  874.              "Command to view a problem report." t)
  875.           (autoload 'unlock-pr "gnats"
  876.              "Unlock a problem report." t)
  877.           (autoload 'query-pr "gnats"
  878.              "Command to query information about problem reports." t)
  879.           (autoload 'send-pr-mode "send-pr"
  880.              "Major mode for sending problem reports." t)
  881.           (autoload 'send-pr "send-pr"
  882.              "Command to create and send a problem report." t)
  883.  
  884.   7. Copy the file `PREFIX/lib/gnats/SITE' from the original host to
  885.      the new host (which may have a different value for PREFIX).  This
  886.      is the list of valid categories that `send-pr' uses (*note Where
  887.      GNATS lives: Locations.).  SITE is your local site, the value of
  888.      `GNATS_SITE' in the `config' file (*note The `config' file:
  889.      config.).
  890.  
  891.  
  892. 
  893. File: gnats.info,  Node: Upgrading,  Prev: Installing tools,  Up: Installation
  894.  
  895. Upgrading from older versions
  896. =============================
  897.  
  898.    If you are upgrading from a previous release of GNATS, you probably
  899. do not want to delete your current configuration files or your current
  900. database.  The new GNATS can be installed around the older version.
  901.  
  902.    You need to:
  903.  
  904.    * Specify your current GNATS_ROOT on the command line to `configure'
  905.      when you build the new tools, with
  906.  
  907.           configure --with-full-gnats --with-gnats-root=GNATS_ROOT
  908.  
  909.      (*Note Configuring and compiling the software: Configure and make.)
  910.  
  911.    * Remove the directory `gnats-bin' from GNATS_ROOT; it is no longer
  912.      used.
  913.  
  914.    * Update your current mail aliases to reflect that `queue-pr' now
  915.      resides in `EXEC-PREFIX/lib/gnats' rather than
  916.      `GNATS_ROOT/gnats-bin' (*note Where GNATS lives: Locations.).
  917.  
  918.    * Change the default `PATH' for the `gnats' user to search the
  919.      directories `EXEC-PREFIX/bin' and `EXEC-PREFIX/lib/gnats'.
  920.  
  921.    * Reinstall the GNATS user tools on all other hosts on your network
  922.      (*note Installing the user tools: Installing tools.).
  923.  
  924.    * Redistribute `send-pr' to your Submitter Sites (*note Configuring
  925.      `send-pr' for the outside world: mkdist.).  This is not absolutely
  926.      necessary, as GNATS can read Problem Reports generated by older
  927.      versions of `send-pr'.  It should be done eventually, however, as
  928.      `send-pr' is improved over older verisons.
  929.  
  930. 
  931. File: gnats.info,  Node: Locations,  Next: Regexps,  Prev: Installation,  Up: Top
  932.  
  933. Where GNATS lives
  934. *****************
  935.  
  936.    We use a few conventions when referring to the installation structure
  937. GNATS uses.  These values are adjustable when you build and install
  938. GNATS (*note Installing GNATS: Installation.).
  939.  
  940. * Menu:
  941.  
  942. * prefix::
  943. * exec-prefix::
  944. * GNATS_ROOT::
  945. * defaults::       Default installation locations
  946.  
  947. 
  948. File: gnats.info,  Node: prefix,  Next: exec-prefix,  Up: Locations
  949.  
  950. PREFIX
  951. ======
  952.  
  953.    PREFIX corresponds to the variable `prefix' for `configure', which
  954. passes it on to the `Makefile' it creates.  PREFIX sets the root
  955. installation directory for "host-independent" files as follows:
  956.  
  957. libraries
  958.      `PREFIX/lib'
  959. `man' pages
  960.      `PREFIX/man'
  961.  
  962. `info' documents
  963.      `PREFIX/info'
  964.  
  965. `include' files
  966.      `PREFIX/include'
  967.  
  968. *etc...*
  969.    The default value for PREFIX is `/usr/local', which can be changed
  970. on the command line to `configure' using
  971.  
  972.      configure --prefix=PREFIX ...
  973.  
  974. *Note Configuring and compiling the software: Configure and make.
  975.  
  976. 
  977. File: gnats.info,  Node: exec-prefix,  Next: GNATS_ROOT,  Prev: prefix,  Up: Locations
  978.  
  979. EXEC-PREFIX
  980. ===========
  981.  
  982.    EXEC-PREFIX corresponds to the variable `exec_prefix' for
  983. `configure', which passes it on to the `Makefile' it creates.
  984. EXEC-PREFIX sets the root installation for "host-dependent" files as
  985. follows:
  986.  
  987. binary tools
  988.      `EXEC-PREFIX/bin'
  989.  
  990. binary support utilities
  991.      `EXEC-PREFIX/lib/gnats'
  992.  
  993. compiled libraries
  994.      `EXEC-PREFIX/lib'
  995. *etc...*
  996.    Since most installations are not intended to be distributed around a
  997. network, the default value for EXEC-PREFIX is the value of `prefix',
  998. i.e., `/usr/local'.  However, using EXEC-PREFIX saves space when you
  999. are installing a package on several different platforms for which many
  1000. files are identical; rather than duplicate them for each host, these
  1001. files can be shared in a common repository, and you can use symbolic
  1002. links on each host to find the host-dependent files.  *It is not
  1003. necessary to use this paradigm when building the GNATS tools*.  *Note
  1004. Configuring and compiling the software: Configure and make.
  1005.  
  1006.    Use EXEC-PREFIX in conjunction with PREFIX to share host-independent
  1007. files, like libraries and `info' documents.  For example:
  1008.  
  1009.         *for each host:*
  1010.      configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
  1011.      make all install ...
  1012.  
  1013. Using this paradigm, all host-dependent binary files are installed into
  1014. `/usr/gnu/H-HOST/bin', while files which do not depend on the host type
  1015. for which they were configured are installed into `/usr/gnu'.
  1016.  
  1017.    You can then use a different symbolic link for `/usr/gnu' on each
  1018. host (`/usr' is usually specific to a particular machine; it is always
  1019. specific to a particular architecture).
  1020.  
  1021.        *on host-1:*
  1022.      ln -s /usr/gnu/H-HOST-1 /usr/gnu
  1023.        *on host-2:*
  1024.      ln -s /usr/gnu/H-HOST-2 /usr/gnu
  1025.  
  1026. To the end user, then, placing `/usr/gnu/bin' in her or his `PATH'
  1027. simply works transparently for each HOST type.
  1028.  
  1029.    You can change EXEC-PREFIX on the command line to `configure' using
  1030.  
  1031.      configure --exec-prefix=EXEC-PREFIX ...
  1032.  
  1033.    We recommend that you consult *Note Using `configure':
  1034. (configure)Using configure, before attempting this.  Again, *it is not
  1035. necessary to use this paradigm when building the GNATS tools*.
  1036.  
  1037. 
  1038. File: gnats.info,  Node: GNATS_ROOT,  Next: defaults,  Prev: exec-prefix,  Up: Locations
  1039.  
  1040. GNATS_ROOT
  1041. ==========
  1042.  
  1043.    The location of the database and the administrative data files, by
  1044. default `PREFIX/lib/gnats/gnats-db'.  You can change this value on the
  1045. command line to `configure' using
  1046.  
  1047.      configure --with-gnats-root=GNATS_ROOT
  1048.  
  1049. Administrative data files reside in `GNATS_ROOT/gnats-adm'.  These
  1050. include `categories', `submitters', `responsible', and `config', as
  1051. well as two files generated and maintained by GNATS, `index' and
  1052. `current'.  *Note Changing your local configuration: Local
  1053. configuration, and *Note Administrative data files: Admin files.
  1054.  
  1055. 
  1056. File: gnats.info,  Node: defaults,  Prev: GNATS_ROOT,  Up: Locations
  1057.  
  1058. Default installation locations
  1059. ==============================
  1060.  
  1061. PREFIX
  1062.      defaults to `/usr/local'; change using `configure' (*note
  1063.      Configuring and compiling the software: Configure and make.).
  1064.  
  1065. EXEC-PREFIX
  1066.      defaults to PREFIX; change using `configure' (*note Configuring
  1067.      and compiling the software: Configure and make.).
  1068.  
  1069. GNATS_ROOT
  1070.      defaults to `PREFIX/lib/gnats/gnats-db'; change using `configure'
  1071.      (*note Configuring and compiling the software: Configure and
  1072.      make.).
  1073.  
  1074. GNATS installs tools, utilities, and files into the following locations.
  1075.  
  1076. `EXEC-PREFIX/bin'
  1077.  
  1078.     `send-pr'
  1079.           *Note Submitting Problem Reports: send-pr.
  1080.  
  1081.     `edit-pr'
  1082.           *Note Editing existing Problem Reports: edit-pr.
  1083.  
  1084.     `query-pr'
  1085.           *Note Querying the database: query-pr.
  1086.  
  1087.     `nquery-pr'
  1088.           *Note Querying the database over the network: query-pr.
  1089.  
  1090. `EXEC-PREFIX/lib/gnats'
  1091.  
  1092.     `mkcat'
  1093.           *Note Adding a problem category: mkcat.
  1094.  
  1095.     `rmcat'
  1096.           *Note Removing a problem category: rmcat.
  1097.  
  1098.     `mkdist'
  1099.           *Note Configuring `send-pr' for the outside world: mkdist.
  1100.  
  1101.     `gen-index'
  1102.           *Note Regenerating the index: gen-index.
  1103.  
  1104.     `queue-pr'
  1105.           *Note Handling incoming traffic: queue-pr.
  1106.  
  1107.     `file-pr'
  1108.           *Note Processing incoming traffic: file-pr.
  1109.  
  1110.     `at-pr'
  1111.           *Note Timely reminders: at-pr.
  1112.  
  1113.     `pr-edit'
  1114.           *Note The `edit-pr' driver: pr-edit.
  1115.  
  1116.     `pr-addr'
  1117.           *Note Address retrieval: pr-addr.
  1118.  
  1119.     `libiberty.a'
  1120.           The GNU `libiberty' library.
  1121.  
  1122. `PREFIX/lib/gnats/dist'
  1123.  
  1124.     A packageable distribution of `send-pr'.
  1125.           *Note Configuring `send-pr' for the outside world: mkdist.
  1126.  
  1127. `PREFIX/lib/gnats'
  1128.  
  1129.     SITE
  1130.           The local list of valid categories, used by `send-pr'; SITE
  1131.           is the value of `GNATS_SITE' (*note The `config' file:
  1132.           config.).
  1133.  
  1134. `PREFIX/lib/emacs/lisp'
  1135.  
  1136.     `gnats.el'
  1137.     `gnats.elc'
  1138.           The Emacs versions of the programs `query-pr', `edit-pr', and
  1139.           `view-pr'.  *Note Invoking the GNATS tools: Invoking the
  1140.           tools.  To change this directory you must alter
  1141.           `Makefile.in'; see *Note Configuring and compiling the
  1142.           software: Configure and make.
  1143.  
  1144.     `send-pr.el'
  1145.           The Emacs version of the program `send-pr'.  *Note Submitting
  1146.           Problem Reports: send-pr.
  1147.  
  1148. `PREFIX/info'
  1149.  
  1150.     `gnats.info'
  1151.     `send-pr.info'
  1152.           The GNATS manuals, in a form readable by `info' (the GNU
  1153.           hypertext browser).  *Note Reading GNU Online Documentation:
  1154.           (infoman)Info.
  1155.  
  1156. `PREFIX/man/man1'
  1157. `PREFIX/man/man8'
  1158.  
  1159.     `man' pages for all the GNATS tools and utilities.
  1160.           *Note Invoking the GNATS tools: Invoking the tools.
  1161.  
  1162. `PREFIX/src'
  1163.  
  1164.     Source code for GNATS.
  1165.  
  1166. `PREFIX/sample'
  1167.  
  1168.     Example administrative files, including `categories',
  1169.           `submitters', `responsible', and `config'.  *Note Changing
  1170.           your local configuration: Local configuration.
  1171.  
  1172. `GNATS_ROOT'
  1173.  
  1174.     `gnats-adm'
  1175.           Administration and configuration data files.  The files
  1176.          `config'
  1177.  
  1178.          `categories'
  1179.  
  1180.          `submitters'
  1181.  
  1182.          `responsible'
  1183.  
  1184.          `gnatsd.conf'
  1185.  
  1186.          `index'
  1187.                (*This file is created by GNATS.*)
  1188.  
  1189.          `current'
  1190.                (*This file is created by GNATS.*)
  1191.  
  1192.           exist here.  *Note Changing your local configuration: Local
  1193.           configuration, and *Note Administrative data files: Admin
  1194.           files.
  1195.  
  1196.     `gnats-queue'
  1197.           Incoming Problem Reports are queued here until the next
  1198.           iteration of `queue-pr -r' (*note Handling incoming traffic:
  1199.           queue-pr.).
  1200.  
  1201.     `pending'
  1202.           Problem Reports which arrive without a valid category value
  1203.           are reassigned to the category `pending' and placed here
  1204.           pending intervention by the GNATS administrator.  *Note GNATS
  1205.           administration: Management.
  1206.  
  1207.     `CATEGORY'
  1208.           Each valid category has a corresponding subdirectory in the
  1209.           database.  All Problem Reports associated with that category
  1210.           are kept in that subdirectory, along with lock files for PRs
  1211.           which are being edited.
  1212.  
  1213. 
  1214. File: gnats.info,  Node: Regexps,  Next: Index,  Prev: Locations,  Up: Top
  1215.  
  1216. Querying using regular expressions
  1217. **********************************
  1218.  
  1219.    GNATS uses GNU regular expression syntax with these settings:
  1220.  
  1221.      RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE
  1222.  
  1223. This means that parentheses (`(' and `)') and pipe symbols (`|') do not
  1224. need to be used with the escape symbol `\'.  The tokens `+' and `?' do
  1225. need the escape symbol, however.
  1226.  
  1227.    Unfortunately, we do not have room in this manual for an adequate
  1228. tutorial on regular expressions.  The following is a basic summary of
  1229. some regular expressions you might wish to use.
  1230.  
  1231.    *Note Regular Expression Syntax: (regex)Regular Expression Syntax,
  1232. for details on regular expression syntax.  Also see *Note Syntax of
  1233. Regular Expressions: (emacs)Regexps, but beware that the syntax for
  1234. regular expressions in Emacs is slightly different.
  1235.  
  1236.    All search criteria options to `query-pr' rely on regular expression
  1237. syntax to construct their search patterns.  For example,
  1238.  
  1239.      query-pr --state=open
  1240.  
  1241. matches all PRs whose `>State:' values match with the regular
  1242. expression `open'.
  1243.  
  1244.    We can substitute the expression `o' for `open', according to GNU
  1245. regular expression syntax.  This matches all values of `>State:' which
  1246. begin with the letter `o'.
  1247.  
  1248.      query-pr --state=o
  1249.  
  1250.    is equivalent to
  1251.  
  1252.      query-pr --state=open
  1253.  
  1254. in this case, since the only value for `>State:' which matches the
  1255. expression `o' is `open'.  (Double quotes (`"') are used to protect the
  1256. asterix (`*') from the shell.)  `--state=o' also matches `o', `oswald',
  1257. and even `oooooo', but none of those values are valid states for a
  1258. Problem Report.
  1259.  
  1260.    Regular expression syntax considers a regexp token surrounded with
  1261. parentheses, as in `(REGEXP)', to be a "group".  This means that
  1262. `(ab)*' matches any number of contiguous instances of `ab', including
  1263. zero.  Matches include `', `ab', and `ababab'.
  1264.  
  1265.    Regular expression syntax considers a regexp token surrounded with
  1266. square brackets, as in `[REGEXP]', to be a "list".  This means that
  1267. `Char[(ley)(lene)(broiled)' matches any of the words `Charley',
  1268. `Charlene', or `Charbroiled' (case is significant; `charbroiled' is not
  1269. matched).
  1270.  
  1271.    Using groups and lists, we see that
  1272.  
  1273.      query-pr --category="gcc|gdb|gas"
  1274.  
  1275. is equivalent to
  1276.  
  1277.      query-pr --category="g(cc|db|as)"
  1278.  
  1279. and is also very similar to
  1280.  
  1281.      query-pr --category="g[cda]"
  1282.  
  1283. with the exception that this last search matches any values which begin
  1284. with `gc', `gd', or `ga'.
  1285.  
  1286.    The `.' character is known as a "wildcard".  `.' matches on any
  1287. single character.  `*' matches the previous character (except
  1288. newlines), list, or group any number of times, including zero.
  1289. Therefore, we can understand `.*' to mean "match zero or more instances
  1290. of any character."  For this reason, we never specify it at the end of
  1291. a regular expression, as that would be redundant.  The expression `o'
  1292. matches any instance of the letter `o' (followed by anything) at the
  1293. beginning of a line, while the expression `o.*' matches any instance of
  1294. the letter `o' at the beginning of a line followed by any number
  1295. (including zero) of any characters.
  1296.  
  1297.    We can also use the expression operator `|' to signify a logical
  1298. `OR', such that
  1299.  
  1300.      query-pr --state="o|a"
  1301.  
  1302. matches all `open' or `analyzed' Problem Reports.  (Double quotes (`"')
  1303. are used to protect the pipe symbol (`|') from the shell.)
  1304.  
  1305.    By the same token,(1) using
  1306.  
  1307.      query-pr --state=".*a"
  1308.  
  1309. matches all values for `>State:' which contain an `a'.  (These include
  1310. `analyzed' and `feedback'.)
  1311.  
  1312.    Another way to understand what wildcards do is to follow them on
  1313. their search for matching text.  By our syntax, `.*' matches any
  1314. character any number of times, including zero.  Therefore, `.*a'
  1315. searches for any group of characters which end with `a', ignoring the
  1316. rest of the field.  `.*a' matches `analyzed' (stopping at the first
  1317. `a') as well as `feedback'.
  1318.  
  1319.    *Note:* When using `--text' or `--multitext', you do not have to
  1320. specify the token `.*' at the beginning of TEXT to match the entire
  1321. field.  For the technically minded, this is because `--text' and
  1322. `--multitext' use `re_search' rather than `re_match'.  `re_match'
  1323. "anchors" the search at the beginning of the field, while `re_search'
  1324. does not anchor the search.
  1325.  
  1326.    For example, to search in the `>Description:' field for the text
  1327.  
  1328.      The defrobulator component returns a nil value.
  1329.  
  1330. we can use
  1331.  
  1332.      query-pr --multitext="defrobulator.*nil"
  1333.  
  1334.    To also match newlines, we have to include the expression `(.|^M)'
  1335. instead of just a dot (`.').  `(.|^M)' matches "any single character
  1336. except a newline (`.') *or* (`|') any newline (`^M')."  This means that
  1337. to search for the text
  1338.  
  1339.      The defrobulator component enters the bifrabulator routine
  1340.      and returns a nil value.
  1341.  
  1342. we must use
  1343.  
  1344.      query-pr --multitext="defrobulator(.|^M)*nil"
  1345.  
  1346.    To generate the newline character `^M', type the following depending
  1347. on your shell:
  1348.  
  1349. `csh'
  1350.      `*control*-V *control*-M'
  1351.  
  1352. `tcsh'
  1353.      `*control*-V *control*-J'
  1354.  
  1355. `sh (*or* bash)'
  1356.      Use the <RETURN> key, as in
  1357.  
  1358.           (.|
  1359.           )
  1360.  
  1361.    Again, see *Note Regular Expression Syntax: (regex)Regular
  1362. Expression Syntax, for a much more complete discussion on regular
  1363. expression syntax.
  1364.  
  1365.    ---------- Footnotes ----------
  1366.  
  1367.    (1) No pun intended.
  1368.  
  1369.